home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Mac Game Programming Gurus / TricksOfTheMacGameProgrammingGurus.iso / More Source / C⁄C++ / CModalProgress 1.1 / Read Me < prev    next >
Text File  |  1995-02-18  |  9KB  |  229 lines
  1. CModalProgress            Read Me
  2. --------------            -------
  3.  
  4. Version 1.1
  5. 18th of February 1995
  6.  
  7. © 1994, 1995 Alysoft Solutions. All rights reserved.
  8.  
  9. The accompanying source code is released as 'freeware'. And as such you
  10. are free to use it in any way that you see fit. The only exception is
  11. that you cannot sell for profit, the source on its own. It is ok to use
  12. the source in other products which are then sold for profit. It is also
  13. reasonable to charge a small amount for downloading from ftp sites etc.
  14. or for the cost of media.
  15.  
  16. Items in this Archive
  17. ---------------------
  18.  
  19. Read Me - This file
  20. CModalProgress.cp - The class source
  21. CModalProgress.h - The classes header file
  22. ProgressDialog.rsrc - The required resourcess for the class
  23.  
  24. CTestDialogs.cp - Example source code
  25. CTestDialogs.h - Header file for examples
  26. main.cp - Main application code for example
  27. TestResources.rsrc - Resources for example
  28.  
  29. ProgressDialog - Example application. This is a 68K binary for running
  30. on a 68k based machine or emulated on a PowerPC machine.
  31.  
  32. Description
  33. ----------
  34.  
  35. The CModalProgress class provides a standard interface for displaying a
  36. Modal dialog during a time intensive task. The progress of the task can
  37. be displayed in the dialog in one of three ways:
  38.   
  39.         • Textual representation of the percent complete
  40.         • A progress bar growing to the right as the task progresses
  41.         • An infinite progress bar (as used by the Finders 'Find' command)
  42.  
  43. Dialog Creation
  44. ---------------
  45.  
  46. The visual appearance of the dialog used by the CModalProgress task is
  47. generated in a standard DLOG and DITL resource. There are several
  48. important items to note:
  49.  
  50.           • Item 1 must be an OK equivalent button
  51.           • Item 2 must be a CANCEL equivalent button
  52.           • Item 3 must be a user item for the OK button outline
  53.  
  54. These items are required for standard keyboard mappings. ie. the OK
  55. button will be activated when Enter or Return are pressed. The CANCEL
  56. button will be activated when ESC or Command-. are pressed.
  57. If this functionality is not required, the buttons should still be
  58. created but they should be disabled and the hidden away from view.
  59.  
  60. If a progress bar or infinite progress bar are required, a user item
  61. should be created for the bar to be drawn into. This item is then passed
  62. to the SetProgressBar() or SetInfiniteBar() methods.
  63.  
  64. If a textual progress indicator is required,  a static text item should
  65. be generated for this purpose. The item number for this static text is
  66. then passed to the SetPercentText() method along with the frequency at
  67. which you want the number to be updated. eg every 1% every 5% every 20%
  68. etc (would take values of 1, 5, 20 repectively). Make sure that this
  69. item is Enabled. If it is not, it will not be used by the clase.
  70.  
  71. Setting of Param text fields (^0 ^1 ^2 ^3) located in the dialog can be 
  72. done in two ways. The easiest is to pass the strings to the SetupDialog()
  73. method. The other method can be used when the class is overridden and the
  74. SetParamText() method is used to set the strings when the standard 
  75. SetupDialog() method is called.
  76.  
  77. Class Use
  78. ---------
  79.  
  80. The progress class breaks the task into separate states each state taking
  81. up a certain percentage of the total task time (except for the infinite
  82. progress bar).
  83.  
  84. Each state contains a resolution or a state space that is set as the task
  85. progresses. eg The Finder's Copy command whould have a read and then a
  86. write state. The state space may correspond to the size of the file, the
  87. copy command would increment the current state value each block that was
  88. read and then written.
  89.  
  90. eg. The Finder Copy Command.
  91.  
  92.       Copying one file that is 128k in size.
  93.  
  94.       • Generate CModalProgress object
  95.       • Provide DLOG resource ID
  96.       • call SetProgressBar() with the user item of the progress bar
  97.       • call SetCurrentState(50), 50 being 50% of total tasks as the first 
  98.         thing we will do is the reading which takes half of the time.
  99.       • call SetStateSpace(128), 128 is our state space. As we read in each 
  100.         1k block of the file we will increment the state value, when it
  101.         reaches 128 we are done.
  102.       • call BeginModal(), start the ball rolling...Show the window.
  103.       • Do read processing, calling SetCurrentStateValue() each block we 
  104.         read.
  105.  
  106. Repeat similar for the write processing
  107.  
  108.       • call SetCurrentState(100), this state goes from 50 up to 100 %
  109.       • call SetStateSpace(128), representing the 128k of data
  110.       • Do the write processing.
  111.       • call EndModal()
  112.       • delete the CModalProgress object
  113.  
  114. The state space for the current state should be set to any value that is
  115. directly related to the processing task. As in the above example, the
  116. state space was set 128 as the data being read in was going to be 128k.
  117. Or if you are processing a text file, the state space may be the number
  118. of lines to process. Then each line that is processed, the modalprogress
  119. object is notified and it updates the progress bar or text accordingly.
  120.  
  121. Event Handling
  122. --------------
  123.  
  124. The CModalProgress class has two ways to handle application events. The 
  125. first and the simplest solution is to let the progress object handle all
  126. events itself, throwing away any event that it does not use. This is
  127. accomplished by calling the ProcessModal() method continualy during
  128. the life of the task.
  129.  
  130. The second method is to pass the events into the progress object by calling
  131. the CanProcessEvent() method. This method will use the event if it was 
  132. actually directed to the dialog and return a value of TRUE to the caller. 
  133. If it does not use the event, then it will return a value of FALSE. This
  134. event can then be passed on to the applications main event loop to be 
  135. processed in the usual way.
  136.  
  137. If this second method is used, then there is another method which will need
  138. to be called periodically if you are using the infinite bar version of
  139. the dialog. The method ProcessIdle() gives the bar some time to draw
  140. itself which was usually done from the ProcessModal() method. If there
  141. is no infinite bar in the dialog (or you continue to use the ProcessModal()
  142. method) then there is no need to call the ProcessIdle() method.
  143.  
  144. NOTE: By looking at the source you may think that the CanProcessEvent()
  145. method already calls the ProcessIdle() method and so you don't need to.
  146. The problem is that the CanProcessEvent() will only get called if you
  147. have an event to pass it (unless you pass lots of null events to it) in
  148. which case the infinite bar would only get drawn when an event is issued.
  149.  
  150.  
  151. Text Substitution
  152. -----------------
  153.  
  154. Text can be substitued into the dialog's static text items in two ways.
  155. There are two versions of the SetupDialog() method, one of which takes
  156. four Str255 parameters, these will be used to make a ParamText() call to
  157. the toolbox before generating the new dialog.
  158.  
  159. The second way to set up static text items is to override the SetParamText()
  160. method. This method is called by the standard SetupDialog() method before
  161. it generates the new dialog. The default version of SetParamText() just
  162. sets all strings to NULL, but by overriding it you can set the strings to
  163. anything you want.
  164.  
  165.  
  166. Other Information
  167. -----------------
  168.  
  169. Forming part of this archive is a small application showing several
  170. examples of how to use the CModalProgress class. The code for these
  171. examples is included for further reference.
  172.  
  173. Registration
  174. ------------
  175.  
  176. As previously stated, this software is 'freeware'. However, if you wish
  177. to register with me that you are using this package, I can forward any
  178. modifications, bug fixes etc to you as soon as they are available.
  179.  
  180. Also, if you find any bugs in the code you can forward reports to me and
  181. will eventually receive updates to fix the problems.
  182.  
  183. Any other form of criticism, suggestions etc will be most welcome.
  184.  
  185.  
  186. Changes from Version 1.0
  187. ------------------------
  188.  
  189. There have been two bug fixes from version 1.0:
  190.  
  191. #1: The class now works correctly in Black and White.
  192. #2: The class will now build and run on PowerMacs.
  193.  
  194. There have been several enhancements to the class:
  195.  
  196. #1: Setting of static text items using ParamText() toolbox routine.
  197. #2: Event processing has been tidied up to provide more compatibility with
  198.     the appliactions main event loop.
  199.  
  200. NOTE: There should be no interface changes from the original Version 1.0
  201. source. You should not need to modify any of your existing code which
  202. used the version 1.0 source.
  203.  
  204. Acknowledments
  205. --------------
  206.  
  207. Thanks must go to the following people for their help with this release:
  208.  
  209. Matthew Moss     - For giving me HEAPS of help fixing the PowerMac problem.
  210. David Plumpton   - For helping to test the PowerMac changes.
  211. Eric Kidd        - For his list of changes and enhacments for the class
  212.                    (sorry I couldn't include them all in this release!).
  213.  
  214. Other People:      Robert Walker, Andy Hong, Aleksandar Totic.
  215.  
  216.  
  217. Contact Address
  218. ---------------
  219.  
  220. Postal:
  221.                  Alysoft Solutions
  222.                  PO Box 387
  223.                  Wollongong East
  224.                  New South Wales      2520
  225.                  Australia.
  226.  
  227. E-Mail:
  228.                  heathcot@bnr.ca
  229.